---
title: Build Images with BuildKit
sidebar_label: buildKit
---

import FragmentBuildOptionsTarget from '../../fragments/build-option-target.mdx';
import FragmentBuildOptionsNetwork from '../../fragments/build-option-network.mdx';
import FragmentBuildOptionsBuildArgs from '../../fragments/build-option-buildArgs.mdx';

Using [BuildKit](https://github.com/moby/buildkit) as build tool allows you to build images either locally or inside your Kubernetes cluster without a Docker daemon. 

:::info
In order to use the build kit you'll either need to have [docker](https://docs.docker.com/get-docker/) installed locally or the [buildx CLI](https://github.com/docker/buildx/releases). **If you only want to use the in cluster build functionality, you won't need a running docker daemon and just need the CLI tools.** 
:::

With `buildKit` enabled, DevSpace will use `docker buildx build` for building. If in cluster building is enabled, DevSpace will deploy a BuildKit deployment into the Kubernetes cluster that will function as target BuildKit daemon for `docker buildx build`. You can also share a single Kubernetes BuildKit daemon across multiple users to share a common build cache.  

To set `buildKit` as default build tool, use the following configuration:
```yaml
images:
  backend:
    image: john/appbackend
    build:
      buildKit: {}
```

## In Cluster Building

If the `inCluster` object is set, DevSpace will build the image directly in the Kubernetes cluster instead of using the local docker daemon. DevSpace will start or reuse a BuildKit deployment in the Kubernetes cluster that acts as target BuildKit daemon. For example:
```yaml
images:
  backend:
    image: john/appbackend
    build:
      buildKit: 
        inCluster: {}
```

**Explanation:**
- `buildKit` tells DevSpace to use the BuildKit engine to build the image.
- `buildKit.inCluster` tells DevSpace to build the image inside the target Kubernetes cluster instead of using the local docker daemon.
- By default, DevSpace will create a BuildKit daemon deployment inside the target namespace that will be used for this and all future builds.

### `inCluster.namespace`

The option takes a string and defines the namespace where to create the BuildKit deployment in. Defaults to the current DevSpace target namespace. 

:::info
By setting `name` and `namespace` you can share a single BuildKit deployment for multiple users. This will have the advantage that a shared build cache is used.
:::

### `inCluster.name`

The option takes a string and defines the name of the BuildKit builder DevSpace will use or create if it does not exist. By default, DevSpace will create a BuildKit builder with the name: devspace-NAMESPACE. For more information about what BuildKit builders are check the [docker docs](https://docs.docker.com/engine/reference/commandline/buildx_create/).

### `inCluster.rootless`

The option takes a boolean and defines if the BuildKit deployment should deploy a non priviledged pod. By default, the BuildKit deployment will try to create a priviledged pod. 

### `inCluster.image`

The option takes a string and defines the docker image to use for the BuildKit deployment.

### `inCluster.nodeSelector`

The option takes a string in the form of `my-label=value,my-label2=value2` that will be used as node selector for the BuildKit deployment.

### `inCluster.noCreate`

The option takes a boolean as value. By default, DevSpace will try to create a new builder if it cannot be found. If this option true, DevSpace will fail if the specified builder cannot be found.

### `inCluster.noRecreate`

The option takes a boolean as value. By default, DevSpace will try to recreate the builder if the builder configuration in the devspace.yaml differs from the actual builder configuration. If this is true, DevSpace will not try to do that.

### `inCluster.noLoad`

The option takes a boolean as value. If image push is disabled (for example by flag `--skip-push` or via `build.buildKit.skipPush`), DevSpace will load the created image into the local docker daemon. If the option is true, DevSpace will not try to do that.

### `inCluster.createArgs`

The option takes a string array as value. These arguments will be appended to the `docker buildx create` command.

## BuildKit options

If `buildKit.inCluster` is omitted, DevSpace will build the image with the local docker daemon and not interact with the Kubernetes cluster. For example:
```yaml
images:
  backend:
    image: john/appbackend
    build:
      buildKit: {}
```

**Explanation:**
- `buildKit` tells DevSpace to use the BuildKit engine to build the image.
- Internally DevSpace will use `docker buildx build` to build the image.

### `skipPush`

The option takes a boolean as value. If this option is enabled, DevSpace will not push the image to the registry. If in cluster build is enabled, DevSpace will try to load the image into the local docker daemon if the image is not pushed.

:::tip
DevSpace will automatically skip image pushing if it detects a local docker daemon such as docker-desktop or minikube. You can disable this behaviour by setting the flag `--skip-push-local-kube=false` 
:::

### `preferMinikube`

The option takes a boolean as value. If this option is disabled, DevSpace will not try to use the minikube docker daemon for image building. This option only has an effect, if minikube is installed and the current kube context is `minikube`.

### `args`

This option takes a string array as value. The arguments will be appended to the `docker buildx build` call DevSpace will run. For example:
```yaml
images:
  backend:
    image: john/appbackend
    build:
      buildKit: 
        args: ["--cache-to", "user/app:cache"]
```

**Explanation:**
- `buildKit` tells DevSpace to use the BuildKit engine to build the image.
- The args option will append arguments to the `docker buildx build` command which will then look something like this: `docker buildx build --tag john/appbackend:DRLzYNS --push --file Dockerfile --cache-to user/app:cache -`
 
### `command`

The option takes a string array as value. By default, DevSpace will use `docker buildx` as base command for interacting with BuildKit, if this option is set, you can tell DevSpace to use a different base command. For example:
```yaml
images:
  backend:
    image: john/appbackend
    build:
      buildKit: 
        command: ["/path/to/my/buildx"]
```
**Explanation:**
- `buildKit` tells DevSpace to use the BuildKit engine to build the image.
- The command option will tell DevSpace to use this command instead of `docker buildx` and the actual build command will look like this: `/path/to/my/buildx build --tag john/appbackend:DRLzYNS --push --file Dockerfile --cache-to user/app:cache -`

## Build Options
DevSpace allows you to configure the following build options:
- `target` defining the build target for multi-stage builds
- `network` to define which network to use during building (e.g. `docker build --network=host`)
- `buildArgs` to pass arguments to the Dockerfile during the build process

### `options.target`

<FragmentBuildOptionsTarget/>


### `options.network`

<FragmentBuildOptionsNetwork/>


### `options.buildArgs`

<FragmentBuildOptionsBuildArgs/>
